home *** CD-ROM | disk | FTP | other *** search
/ Acorn User: The Risc OS Music Utilities CD / Acorn User: The Risc OS Music Utilities CD.iso / UTILITIES / SYSEXY / !SysExy / !Help < prev    next >
Text File  |  2000-04-14  |  18KB  |  455 lines
  1.  
  2. —————————————————————————————  !SysExy (0.34)  —————————————————————————————
  3.  
  4.                           Copyright, MidiWays 1999
  5.  
  6.                                Author : Lenny
  7.  
  8. ————————————————————————————————————————————————————————————————————————————
  9.  
  10. 0.0  Contents
  11.      ========
  12.  
  13.      1.0  Overview
  14.      1.1    System requirements
  15.      1.2    Software status
  16.      2.0  Iconbar
  17.      3.0  The Panel window
  18.      4.0  The Options window
  19.      5.0  MIDI connections
  20.      6.0  Identifying System Exclusive messages
  21.      7.0  Creating System Exclusive data using a text editor
  22.      8.0  Embedding System Exclusive data within MIDIfiles
  23.      9.0  Contacting the author
  24.  
  25. ————————————————————————————————————————————————————————————————————————————
  26.  
  27. 1.0  Overview
  28.      ========
  29.  
  30. System Exclusive messages are a specific type of MIDI message.  They have
  31. a broad range of uses and fall into two main categories - Universal and
  32. manufacturer specific.  Universal messages (Real Time and Non Real Time)
  33. affect all (applicable) devices within the MIDI system, whereas
  34. manufacturer specific messages are targeted towards specific devices.
  35.  
  36. Thus Universal messages are involved with system setup type operations,
  37. whereas manufacturer specific messages are involved with setting up
  38. individual devices.
  39.  
  40. This application enables MIDI system exclusive messages to be captured
  41. over MIDI, and stored as files on disc for later re-transmission over
  42. MIDI.  It functions therefore as a MIDI Data Recorder (MDR).
  43.  
  44. Note that I use the term 'packet' to mean 'system exclusive message'.
  45.  
  46. It uses its own filetype (&770) for system exclusive data.  These SysEx
  47. files are chunk based, capable of containing multiple packets.
  48.  
  49.   Eg.  The Roland R8 drum machine has a system exclusive command to
  50.        request a dump of the R8's entire setup memory.  This dump
  51.        comprises 30 packets which collectively make up the setup memory
  52.        contents.
  53.        These 30 packets can be captured and saved as a single multi-packet
  54.        SysEx file, thus providing a self-contained record of that
  55.        particular R8 setup.  Similarly with the R8's sequence (drum
  56.        pattern) memory, ie a SysEx file containing the R8's sequence dump
  57.        could be saved for each song project (so that you can always go
  58.        back to a project at some later date).
  59.  
  60. That last point is !SysExy's main function - to capture 'snapshots' of a
  61. MIDI device's memory contents, and to enable creation of a disc-based
  62. library of such snapshots.
  63.  
  64. The program allows a maximum of 500 system exclusive messages or 64k of
  65. data to be held in memory (whichever limit is reached first).  Sorry - no
  66. dynamic memory management in this respect.
  67.  
  68. System exclusive messages can also be exported as MIDIFiles, enabling (for
  69. example) synthesiser voice definitions which were originally captured with
  70. !SysExy, to be loaded into a sequencer (eg !MidiWorks or !MelIDI) and thus
  71. embedded within the song which requires those particular voices.  This
  72. feature is mainly of use if you like to define your own instrument sounds,
  73. rather than relying on the presets provided in your synthesiser.
  74.  
  75. It is also possible to use a text editor (eg !Zap) to create a textual
  76. representation (a sequence of hex pairs) of a system exclusive message,
  77. which can be loaded into !SysExy.
  78.  
  79. Interactive Help is supported, so run !Help (or !BubbleHlp, etc) when
  80. first trying out the program.
  81.  
  82. The program has been written as a MIDISupport plugin.
  83.  
  84.  
  85. 1.1  System requirements
  86.      ===================
  87.  
  88. To use !SysExy, ESP's MIDISupport module (0.30, or later) and !MidiMan
  89. (the front end application that is supplied as part of the MIDI Support
  90. package) are both required.
  91.  
  92. It runs on my StrongARM'd RiscPC with RISC OS 4.02.
  93.  
  94. I don't think there's anything RiscPC specific in the code, so it should
  95. run on any machine equipped with RISC OS 3.10, or later.
  96.  
  97.  
  98. 1.2  Software status
  99.      ===============
  100.  
  101. This software is not PD ...
  102.  
  103.  ... It is Freeware.
  104.  
  105. That is, I retain the copyright, though it may be freely distributed.
  106.  
  107. Please, refer to the file 'Licence' within the '<SysExy$Dir>.Docs'
  108. directory.
  109.  
  110. ————————————————————————————————————————————————————————————————————————————
  111.  
  112. 2.0  Iconbar
  113.      =======
  114.  
  115. * Click SELECT on the iconbar icon to Open/Surface the Panel window.
  116.  
  117. * Click ADJUST on the iconbar icon to Open/Close the Panel window.
  118.  
  119.   Use the CTRL key with SELECT/ADJUST to open/surface/close the Options
  120.   window.
  121.  
  122.   Use the SHIFT key with SELECT/ADJUST to open/surface/close both windows.
  123.  
  124. * Click MENU on the iconbar icon to open the iconbar menu.
  125.  
  126.   This contains 4 items : Info, Options…, Clear and Quit.
  127.  
  128.   Info and Quit do the usual, Options… opens the User Options window, and
  129.   Clear removes from memory all currently loaded system exclusive
  130.   messages.
  131.  
  132.   Note that no warning is given about losing unsaved data upon selecting
  133.   Quit.
  134.  
  135. ————————————————————————————————————————————————————————————————————————————
  136.  
  137. 3.0  The Panel window
  138.      ================
  139.  
  140. All of the main functions of the program are accessed directly from this
  141. window - there is no menu for this window, and hence no popup save window.
  142.  
  143. Of the two immediately visible sections, the top is split into 3 areas
  144. whilst the bottom section contains the main action buttons.
  145.  
  146. The top section :
  147.  
  148.  * The top area indicates the number of packets currently in memory, and
  149.    provides a switch enabling the reception of MIDI data to be toggled on
  150.    and off (when Listen is ticked, any system exclusive messages arriving
  151.    at !SysExy's MIDI input will be captured.  (See the MIDI Connections
  152.    section.)
  153.  
  154.  * The middle area provides basic information about a single packet : its
  155.    length (decimal and hex), its ID, and up to 10 bytes of the message.
  156.  
  157.    In the case of System Exclusive messages that are longer than 10 bytes,
  158.    the message can be scrolled through using the bump icons next to the
  159.    bytes list.  The number immediately to the right shows the offset into
  160.    the message.
  161.  
  162.  * The bottom area (Cluster) enables a group of consecutive packets to be
  163.    treated en masse.
  164.  
  165. Note that holding down the SHIFT key whilst clicking on any of the bump
  166. icons (packet selection, byte offset and setting the clustered range) will
  167. speed up the rate of change of the associated parameter.
  168.  
  169. The bottom (action button) section :
  170.  
  171.  * 2 file icons (for saving MIDI and SysEx files respectively).
  172.  
  173.    A packet (or cluster) can be saved to disc either as a SysEx file or as
  174.    a MIDIFile (for exporting system exclusive messages into sequencers) by
  175.    dragging the appropriate file icon to the required filer window.
  176.  
  177.  * A writeable icon for entering the filename.
  178.  
  179.  * Save : To save packet(s) as a SysEx file (similarly if the RETURN key
  180.    is pressed whilst the caret is in the filename icon).
  181.  
  182.  * Remove : To remove packet(s) from memory.
  183.  
  184.  * Tx : To transmit packet(s) over MIDI.
  185.  
  186. Note that each of these last three functions along with drag saving take
  187. account of the 'Cluster' setting.  If Cluster is ticked then the range of
  188. packets specified in that section will be saved/removed/transmitted. 
  189. Otherwise the single packet shown in the middle area will be
  190. saved/removed/transmitted.
  191.  
  192. There is a third section which appears only whilst transmitting MIDI data. 
  193. This section gives information about the packet currently being
  194. transmitted, and provides a single button Abort, which can be used to
  195. interrupt the transmission of a clustered group of packets (interruption
  196. occurs between packets, not in the midst of one).
  197.  
  198. Note that the action buttons other than Abort are disabled, and MIDI
  199. reception is temporarily suspended, whilst transmission is in progress.
  200.  
  201. Closing the Panel window does not lose any data currently held in memory.
  202.  
  203. ————————————————————————————————————————————————————————————————————————————
  204.  
  205. 4.0  The Options window
  206.      ==================
  207.  
  208. The user preferences may be set here.  They can also be saved so that they
  209. will be used as the default settings in subsequent sessions.
  210.  
  211. The upper section contains two settings, the effect of which will not be
  212. apparent until the next time !SysExy is run (provided the options are
  213. saved, that is).
  214.  
  215.  * Open Panel : If ticked, the Panel window will be opened upon running
  216.    !SysExy.
  217.  
  218.  * Listen : This specifies the initial setting of the Listen switch in the
  219.    Panel window.
  220.  
  221. The lower section contains settings which will take immediate effect.
  222.  
  223.  * Load action : Retain / Tx.  These determine what happens when loading a
  224.    SysEx (or suitable Text) file.  Files dragged to the iconbar or Panel
  225.    window can be treated transiently and immediately transmitted over MIDI,
  226.    or retained in memory (for inspection, grouping or un-grouping), as
  227.    determined by this option.
  228.  
  229.    Note that it is possible to set both options (ie Retain and Tx).
  230.  
  231.  * Open Panel upon load : If ticked, the Panel window will be opened when
  232.    loading a SysEx (or suitable Text) file (provided that Load Action
  233.    'Retain' is ticked).
  234.  
  235.    If the Load Action is set to Tx only, and a SysEx file is dragged to
  236.    the iconbar whilst the Panel window is closed, then the Panel will be
  237.    opened just for the duration of the transmission process.
  238.  
  239.  * Open Panel upon Rx : If ticked, the Panel window will be opened when a
  240.    packet is received via MIDI (this also requires that the Listen switch
  241.    in the Panel window is ticked, and that appropriate MIDI 'connections'
  242.    are setup using !MidiMan).
  243.  
  244.  * MIDIfile : When exporting packets as a MIDIfile, this option specifies
  245.    whether multiple packets should be placed sequentially within a single
  246.    track, or in separate tracks.
  247.  
  248.  * Export type : This is somewhat esoteric and is included for
  249.    completeness more than anything else.  The Standard setting should
  250.    generally be used.
  251.  
  252.    The MIDI specification describes two methods of embedding a system
  253.    exclusive message within a MIDIFile : a) 'standard' and b) 'escape'.
  254.      a) F0 <len> <remaining bytes, inc F7>
  255.      b) F7 <len> <entire system exclusive message: F0 - F7>
  256.  
  257.    where <len> is a variable length value providing a count of the bytes
  258.    which follow, up to and including the F7.
  259.  
  260.    Eg the message "F0 43 12 00 07 F7" would be coded :
  261.      a) F0 05 43 12 00 07 F7
  262.      b) F7 06 F0 43 12 00 07 F7
  263.  
  264.  * Inter-packet delay : This affects transmission of multiple packets.
  265.    Some MIDI hardware cannot cope with receiving a quick succession of
  266.    system exclusive messages, and needs to be given enough time to process
  267.    the incoming MIDI data.  This option allows the user to specify a delay
  268.    (in centiseconds) between adjacent packets.
  269.  
  270. In the absence of a !Config file, !SysExy will start up using its internal
  271. defaults :
  272.  
  273.  * Open Panel : Yes
  274.  * Listen     : No
  275.  
  276.  * Load action : Retain
  277.  * Open Panel upon Load : Yes
  278.  * Open Panel upon Rx   : Yes
  279.  * MIDIfile : All packets on one track
  280.  * Export type : Standard
  281.  * Inter-packet delay : 20 cs
  282.  
  283. ————————————————————————————————————————————————————————————————————————————
  284.  
  285. 5.0  MIDI connections
  286.      ================
  287.  
  288. !SysExy can both send and receive MIDI data, a software MIDI driver (named
  289. 'SysExy') being created for this purpose.  This driver needs to be
  290. connected into the MIDI Support system.
  291.  
  292. Whilst !SysExy is running, call up !MidiMan's Routing window and use its
  293. Source and Destination popup menus to connect the SysExy driver to the
  294. required driver(s).
  295.  
  296. If you wish to exchange data with an external MIDI device, then you would
  297. connect SysExy's driver to the relevant hardware MIDI driver for your
  298. setup.  Eg AKA16_1 (if using an Acorn AKA16 MIDI card) or DMI50PortA_1 /
  299. DMI50PortB_1 (if using a DMI50 card), etc. for both send and receive.
  300.  
  301. However, you could just as easily exchange data with another MIDI Support
  302. aware application by connecting SysExy to its driver.
  303.  
  304. Once set up in this way, the setting of the Listen toggle in the Panel
  305. window determines whether the MIDI input is actually monitored for the
  306. arrival of system exclusive data.  If ticked, then arriving messages are
  307. captured and stored in memory.
  308.  
  309. The program will beep upon receiving a system exclusive message that would
  310. exceed either limit of 500 messages or 64k of data.
  311.  
  312. ————————————————————————————————————————————————————————————————————————————
  313.  
  314. 6.0  Identifying System Exclusive messages
  315.      =====================================
  316.  
  317. This aspect of the program is user extendable, by way of the files present
  318. in the '<SysExy$Dir>.IDs' directory.
  319.  
  320. The file '!_Manus' lists manufacturer ID codes.  This file MUST be
  321. present.  The supplied copy contains just a short list of the more common
  322. manufacturers, though you can extend this (up to 64 manufacturers).  This
  323. file enables !SysExy to make basic identification of system exclusive
  324. messages - at the level of manufacturer/universal type.
  325.  
  326. The remaining (optional) files (one per manufacturer) must (if present)
  327. have the same filename as the name specified in the '!_Manus' file.
  328.  
  329. These files enable !SysExy to make a more precise identification of system
  330. exclusive messages.  The contents are a series of lines each comprising a
  331. pattern of bytes to be matched and a textual description of the packet's
  332. usage.  Comments (lines beginning with a '#') and blank lines are ignored.
  333.  
  334. Each valid line has the general form :
  335.  
  336.   <comparison pattern>: <reported text>
  337.  
  338. ie any text preceding the first ':' is the comparison pattern.
  339.  
  340. The <comparison pattern> has the following format/syntax :
  341.  
  342.  * The first element specifies the byte (within the system exclusive
  343.    message) from which to start the comparison.
  344.    Eg.  B2=  specifies to start the comparison from the second byte.
  345.  
  346.  * There then follows a list of /consecutive/ comma (or space) separated
  347.    hex digit pairs (maximum of 16 hex pairs).
  348.    Note that a value of 'xx' means ignore/skip this byte.
  349.    If one of the hex digits is specified as 'n' then this nibble will be
  350.    masked out in any comparison.
  351.    Eg.  2n  will match 20..2F.
  352.  
  353. The <reported text> should be 31 chars max.  Any spaces between the ':'
  354. and the first non space character of the reported text are ignored.
  355.  
  356. Refer to the supplied files for example usage.
  357.  
  358.  
  359. For Zap users :
  360. ~~~~~~~~~~~~~
  361. You may like to add the following line
  362.  
  363. &500        &FFF    \#\*.IDs.\o\*        +Messages
  364.  
  365. to your '!ZapUser.Config.TypesLow' file.
  366.  
  367. This will apply syntax colouring to the files in the '<SysExy$Dir>.IDs'
  368. directory.
  369.  
  370. ————————————————————————————————————————————————————————————————————————————
  371.  
  372. 7.0  Creating System Exclusive data using a text editor
  373.      ==================================================
  374.  
  375. There are some situations which require the use of a system exclusive
  376. message which it is not possible to capture from a MIDI device.  Eg many
  377. devices will respond to a 'dump request' type message though may not ever
  378. issue such a message themselves.
  379.  
  380. !SysExy is able to interpret a suitably formatted Text file which
  381. describes a system exclusive message, thus any message can be created
  382. using a text editor.
  383.  
  384. The contents of the Text file should follow this description :
  385.  
  386.  * The data is represented as 2-digit hex characters separated by spaces,
  387.    commas or linefeeds.
  388.  
  389.  * Comments can be introduced within the Text file with a '|' character.
  390.    If it is not the first character on the line, it must be immediately
  391.    preceded by a separator (space or comma), ie it must not be butted up
  392.    against the data.  The remainder of the line is treated as a comment.
  393.  
  394.  * Additional spaces within the Text file (for aligning comments, etc) are
  395.    allowed, and ignored appropriately.
  396.  
  397. The file should describe just a single system exclusive message - multiple
  398. packets are not allowed for.
  399.  
  400. Upon loading such a file into !SysExy, it is checked to see that it
  401. contains valid data, ie that the interpreted data starts with &F0 and ends
  402. with &F7.
  403.  
  404. Some example Text files are supplied in the 'Extra' directory.
  405.  
  406. ————————————————————————————————————————————————————————————————————————————
  407.  
  408. 8.0  Embedding System Exclusive data within MIDIfiles
  409.      ================================================
  410.  
  411. It is often desirable to embed system exclusive data within a MIDIfile,
  412. for example to ensure that the appropriate voice definitions are set up
  413. for a particular sequence.
  414.  
  415. This does of course require the use of a sequencer which can cope with
  416. system exclusive data, such as !MidiWorks or !MelIDI.
  417.  
  418. However, even with sequencers that do not directly cater for system
  419. exclusive data (eg !Anthem), !SysExy can be 'manually' used alongside to
  420. transfer the required system exclusive data prior to actually playing the
  421. sequence.
  422.  
  423. When exporting multiple packets as a MIDIfile, !SysExy will place the
  424. individual packets either in a single track (at 4 bar intervals) or in
  425. separate tracks (as determined by the MIDIfile option).
  426.  
  427. You should take care not to exceed your sequencer's number of tracks
  428. capability when exporting multiple packets with the 'one packet per track'
  429. option set.  For example, attempting to load a 20 packet MIDIfile (saved
  430. using one packet per track) into !Serenade will lose the last four
  431. packets, as !Serenade is a 16 track sequencer.
  432.  
  433. Apart from that proviso, it is fairly arbitrary which method you use, as
  434. you will invariably want to move the packets around (which track and
  435. position within that track) using the sequencer's copy/move facilities.
  436.  
  437. ————————————————————————————————————————————————————————————————————————————
  438.  
  439. 9.0  Contacting the author
  440.      =====================
  441.  
  442. For bug reports, suggestions, sighs of adulation, derisive comments or
  443. submission of gratuities, please contact :
  444.  
  445.   snail:  Lenny
  446.           MidiWays
  447.           204 Amelia Street
  448.           Walworth
  449.           London
  450.           SE17 3AS
  451.  
  452.   email:  lenny@argonet.co.uk
  453.  
  454. ————————————————————————————————————————————————————————————————————————————
  455.